LESSON 6: Enabling Versioning

Objective:
In this tutorial you will learn how to enable the new support for 'versioning', which enables wiki-type editing, with history, feature differences and rollbacks. You will put data in to PostGIS, enable versioning to alter the table structure, play with sample requests, and make an OpenLayers editing environment around it.

Step 0: Start PostGIS and set paths

If PostGIS is already on or the path is already set you can skip this step.

Set PostGIS on the path.
1. Open a Command Line by navigating from StartMenu->Run..., and typing "cmd"
2. Try typing 'psql'. If you don't get 'psql is not recognized...' skip to step 'Start PostGIS'. If not then do the next step.
3. Navigate to C:\foss4g2007\workshop-04
  
  cd C:\foss4g2007\workshop-04
4. run 'pg_setenv.bat'
  
  C:\foss4g2007\workshop-04>pg_setenv.bat

Start PostGIS
1. Go to the Start Menu
2. Under PostgreSQL 8.2 select 'Start service'
3. If you execute the "psql" command and get a password prompt, everything is correctly configured.

Step 1: Create the database

Make sure PostGIS is available by trying 'psql' from the command line
Create a "spearfish" superuser with spearfish password:

createuser -s -d -P -U postgres spearfish

Enter 'spearfish' for the 'password for new roll' (and 'Enter it again') and 'postgres' for the password to do the creation.
Note: if you get an error message could not find a "createuser" to execute, you can safely ignore this.
Create a PostGIS enabled speafish database:

createdb spearfish -U spearfish -T template_postgis

Use 'spearfish' for the password. If the command above fails use

createdb spearfish -U postgres
createlang plpgsql -U postgres spearfish
psql -U postgres -d spearfish -f /usr/share/lwpostgis.sql
psql -U postgres -d spearfish -f /usr/share/spatial_ref_sys.sql
Navigate to C:\Program Files\GeoServer 1.6-beta3\data_dir
Restore the sample database:

psql -U spearfish spearfish < spearfish.sql

Step 2: Version Enable the Database

Go to your GeoServer web admin at http://localhost:8080/geoserver
Go to create a new DataStore
Select 'Versioning Postgis' and name it sf
Fill out the parameters
## Use the defaults of localhost and 5432
1. Use spearfish for the database, and spearfish/spearfish for username and password
2. Be SURE to set 'version enable all' to true, as this creates the versioning tables you need.
Create new featureTypes like you did with the shapefile, but this time you have to navigate to FeatureTypes and hit 'New', and find your new featureTypes to create there. Let's create:
1. sf:roads, select simple_roads style, generate bbox, submit
2. sf:archsites, select point style, generate bbox, submit
3. sf:restricted, select rescricted style, generate bbox, submit
4. Click Apply, and Save

Step 3: Sample Requests Walkthrough

Though we are working on tools in OpenLayers and eventually other platforms to abstract these all away, we want to show you a bit of what's going on behind the scenes.

From the main web-admin page, http://localhost:8080/geoserver/welcome.do, go to the Demo section and then 'Sample Requests'
The requests there are given in order, so walk through them one by one, or they won't have the same effect as advertised.

Step 4: Experiment with an OpenLayers Feature Editor

In this step, you'll try out a sample Feature Editor application with OpenLayers. The application was developed for this workshop and has not been rigorously tested. You'll likely notice some awkward workflow and maybe a bug or two.

Prerequisites

Versioning enabled on the Spearfish database.
Firefox with Firebug installed.

Adding a new feature

Find the feature-editor.html file in your (config_dir)/www directory. In this case it should be C:\Program Files\GeoServer 1.6.0-beta3\www. Open http://localhost:8080/geoserver/www/feature-editor.html to view this page. You should be looking at imagery from Spearfish, North Dakota with some red polygons over top. The polygons come via WMS from the topp:restricted layer in the spearfish database.
The five tools at the top right are (from left to right), a navigation tool (hand), a feature drawing tool (pencil), a feature selection tool (box), a feature modification tool (move arrows), and a save buttom (floppy disk).
With the navigation tool active, shift-drag to zoom in, click-drag to pan. Navigate to an interesting area on the map. Note that navigation is restricted to the initial bounds (you can't drag beyond a certain point).
Activate the drawing tool and digitize a new polygon (click to add points, double-click to finish).
Click the save button to save your features (this button gives no real feedback). If it works, you should see your sketch disappear and the Restricted Areas layer redrawn with your new polygon included.
Open Firebug to see a record of the transactions that have been made (F12 or click the green circled check at the lower right). After the console is open, you can click the ^ button to open Firebug in it's own window. Find and expand the last request (labeled POST http://localhost:8080/geoserver/...).  Click the Post tab to see a record of the posted transaction. You should be able to identify an Insert element and the MultiPolygon geometry. This request was sent from the client side (this feature-editor.html page) to GeoServer. Click the Response tab to see what came back from GeoServer. You should be able to identify the SUCCESS element.

Modifying existing features

Back in the main browser window, activate the selection tool and click-drag a box that intersects multiple polygons. In Firebug, you can watch the getFeature request go by (a GET request) and the response from GeoServer. You use this selection tool to determine which features are available for editing on the client side.
Use the modify feature tool to begin modifying one of the selected polygons. The first click will make vertices available for dragging. You can add a vertex along an edge by dragging one of the virtual virtices (slightly more transparent than the others). Modify a polygon and click the save button. Be patient while the Restricted Areas layer (WMS) is redrawn with your modified polygon.

Log messages and editing attributes

On the Editing Options menu, choose Preferences. In the preferences dialog, click Require log messages. Following the two steps above, select features for editing, modify a feature, and click the save button. You should be prompted to enter a message about your modification. Enter a message and watch in Firebug as this message is added to the handle attribute of the Transaction element (in the Post tab).
From the preferences dialog again, choose to Edit attributes and save options. Modify a feature again. This time you will be presented with a dialog to edit the feature attributes if you want. Change the attributes of a feature and save. Again, take a look at the posted transaction in Firebug. (Note that even if you didn't modify the geometry, it will be updated in the transaction. This is not necessary and will be improved.)

History, diffs, and rollbacks

Under Editing Options, open the View History dialog. This is somewhat similar to a wiki page history if you're familiar with that. Clicking on a revision will roll back changes for the editable layer. Clicking the "Compare" button (at the bottom) will show you the difference between the "From" and "To" revision. Explore the differences between the various revisions that you have made.
Add a new feature and save. Next modify that feature and save. Now open the history dialog and rollback to previous revisions to undo your edits. Roll back to a revision that removes your new feature. Roll back to a revision that brings your feature back.

Adding new layers

Now, open feature-editor.html in a text editor. Find the section that defines the layers available to the editor. The layers defined in the editor allow it to add the appropriate WMS layers to the map and make correct WFS requests. The editor relies on paired WFS and WMS services (representing the same data, named the same way). The syntax for defining a new layer for the editor requires you know the layers name (layer name in WMS and FeatureType typeName in WFS - with namespace alias), the geometry type, and the schema for the features. You also choose a title for the layer to be used in the application. The schema is a JavaScript object with one property per feature. So the schema for a road feature that had two attributes, type and lanes, where type was a string and lanes was a long integer, would look like this

{ "type": "string", "lanes": "long" }

The new layer configuration should look like:
```
{
    title: "Roads",
    name: "topp:roads",
    type: "MultiLineString",
    schema: {
        "type": "string",
        "lanes": "long"
    }
}
```
The end result should look like:
```
{
    Editor.layers = [
    {
          title: "Restricted Areas",
          name: "topp:restricted",
          type: "MultiPolygon",
          schema: {
              "cat": "long"
          }
    },
    {
    title: "Roads",
    name: "topp:roads",
    type: "MultiLineString",
    schema: {
       "type": "string",
       "lanes": "long"
    }
}
```
Make a number of edits to each layer: modifying features, adding new features, and changing attributes. View the history of your changes. View differences between specific versions (for the editable layer). Roll back to an older revision (for the editable layer).

Extra Credit

Try out transparent versioning - GeoServer's versioning supports normal WFS-T requests, and automatically makes versions of them, though without nice commit messages and the like, and no ability to do rollbacks or see the history. But try out uDig and connect it to the GeoServer versioned features. You can also make 'changesets' a featureType that WFS clients can look at, so you can turn that on in GeoServer and play with it in uDig.

Turn versioning on for streams - For this you'll have to remove your streams shapefile featureType, or else just change its namespace. After you do that you can use shp2pgsql to insert it into the versioning database (be sure to get the SRS code right). Then you can try to get it version enabled and overlaid as another editable, versioned layer on OpenLayers.

Attachments:

sf-NewDataStore.png (image/png)

sf-VersioningPostgisConfiguration.png (image/png)

sf-DataStores.png (image/png)

Document generated by Confluence on Jan 16, 2008 23:27